home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat2 / standard / attr_multi.z / attr_multi
Encoding:
Text File  |  2002-10-03  |  16.2 KB  |  265 lines
  1.  
  2.  
  3.  
  4. AAAATTTTTTTTRRRR____MMMMUUUULLLLTTTTIIII((((2222))))                                                    AAAATTTTTTTTRRRR____MMMMUUUULLLLTTTTIIII((((2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      attr_multi, attr_multif - manipulate multiple user attributes on a
  10.      filesystem object at once
  11.  
  12. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////aaaattttttttrrrriiiibbbbuuuutttteeeessss....hhhh>>>>
  14.  
  15.      iiiinnnntttt aaaattttttttrrrr____mmmmuuuullllttttiiii ((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ppppaaaatttthhhh,,,, aaaattttttttrrrr____mmmmuuuullllttttiiiioooopppp____tttt ****oooopppplllliiiisssstttt,,,,
  16.                      iiiinnnntttt ccccoooouuuunnnntttt,,,, iiiinnnntttt ffffllllaaaaggggssss))));;;;
  17.  
  18.      iiiinnnntttt aaaattttttttrrrr____mmmmuuuullllttttiiiiffff ((((iiiinnnntttt ffffdddd,,,, aaaattttttttrrrr____mmmmuuuullllttttiiiioooopppp____tttt ****oooopppplllliiiisssstttt,,,,
  19.                       iiiinnnntttt ccccoooouuuunnnntttt,,,, iiiinnnntttt ffffllllaaaaggggssss))));;;;
  20.  
  21. OOOOVVVVEEEERRRRVVVVIIIIEEEEWWWW
  22.      The _a_t_t_r group of system calls implement the ability for a user to attach
  23.      name/value pairs to objects within the filesystem.
  24.  
  25.      They could be used to store meta-information about the file.  For example
  26.      "character-set=kanji" could tell a document browser to use the Kanji
  27.      character set when displaying that document and "thumbnail=..." could
  28.      provide a reduced resolution overview of a high resolution graphic image.
  29.  
  30.      The _n_a_m_e_s can be up to MAXNAMELEN bytes in length, terminated by the
  31.      first 0 byte.  The intent is that they be printable ASCII (or other
  32.      character set) names for the attribute.
  33.  
  34.      The _v_a_l_u_e_s can be up to ATTR_MAX_VALUELEN (currently 64KB) of arbitrary
  35.      binary data.
  36.  
  37.      Attributes can be attached to all types of inodes:  regular files,
  38.      directories, symbolic links, device nodes, etc.
  39.  
  40.      There are 2 disjoint attribute name spaces associated with every
  41.      filesystem object.  They are the rrrrooooooootttt and uuuusssseeeerrrr address spaces.  The rrrrooooooootttt
  42.      address space is accessible only to privileged users, and only then by
  43.      specifying a flag argument to the function call.  A privileged user can
  44.      be either the superuser in an IIIIRRRRIIIIXXXX environment, or a user with
  45.      CCCCAAAAPPPP____DDDDEEEEVVVVIIIICCCCEEEE____MMMMGGGGTTTT capability.  Other users will not see or be able to modify
  46.      attributes in the rrrrooooooootttt address space.  The uuuusssseeeerrrr address space is
  47.      protected by the normal file permissions mechanism, so the owner of the
  48.      file can decide who is able to see and/or modify the value of attributes
  49.      on any particular file.
  50.  
  51.      Attributes are currently fully supported only in the XFS and CXFS
  52.      filesystem types.  Other filesystem types may provide a partial
  53.      implementation.
  54.  
  55. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  56.      The _a_t_t_r__m_u_l_t_i and _a_t_t_r__m_u_l_t_i_f functions provide a way to operate on
  57.      multiple attributes of a filesystem object at once.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. AAAATTTTTTTTRRRR____MMMMUUUULLLLTTTTIIII((((2222))))                                                    AAAATTTTTTTTRRRR____MMMMUUUULLLLTTTTIIII((((2222))))
  71.  
  72.  
  73.  
  74.      _P_a_t_h points to a path name for a filesystem object, and _f_d refers to the
  75.      file descriptor associated with a file.  The _o_p_l_i_s_t is an array of
  76.      _aaaa_tttt_tttt_rrrr______mmmm_uuuu_llll_tttt_iiii_oooo_pppp______tttt structures.  Each element in that array describes a single
  77.      attribute operation and provides all the information required to carry
  78.      out that operation and to check for success or failure of that operation.
  79.      _C_o_u_n_t tells how many elements are in the _o_p_l_i_s_t array.
  80.  
  81.      The contents of an _aaaa_tttt_tttt_rrrr______mmmm_uuuu_llll_tttt_iiii_oooo_pppp______tttt structure include the following
  82.      members:
  83.  
  84.         _iiii_nnnn_tttt _aaaa_mmmm______oooo_pppp_cccc_oooo_dddd_eeee_;;;; _////_**** _wwww_hhhh_iiii_cccc_hhhh _oooo_pppp_eeee_rrrr_aaaa_tttt_iiii_oooo_nnnn _tttt_oooo _pppp_eeee_rrrr_ffff_oooo_rrrr_mmmm _((((_ssss_eeee_eeee _bbbb_eeee_llll_oooo_wwww_)))) _****_////
  85.         _iiii_nnnn_tttt _aaaa_mmmm______eeee_rrrr_rrrr_oooo_rrrr_;;;; _////_**** _[[[[_oooo_uuuu_tttt _aaaa_rrrr_gggg_]]]] _rrrr_eeee_ssss_uuuu_llll_tttt _oooo_ffff _tttt_hhhh_iiii_ssss _ssss_uuuu_bbbb_----_oooo_pppp _((((_aaaa_nnnn _eeee_rrrr_rrrr_nnnn_oooo_)))) _****_////
  86.         _cccc_hhhh_aaaa_rrrr _****_aaaa_mmmm______aaaa_tttt_tttt_rrrr_nnnn_aaaa_mmmm_eeee_;;;; _////_**** _aaaa_tttt_tttt_rrrr_iiii_bbbb_uuuu_tttt_eeee _nnnn_aaaa_mmmm_eeee _tttt_oooo _wwww_oooo_rrrr_kkkk _wwww_iiii_tttt_hhhh _****_////
  87.         _cccc_hhhh_aaaa_rrrr _****_aaaa_mmmm______aaaa_tttt_tttt_rrrr_vvvv_aaaa_llll_uuuu_eeee_;;;; _////_**** _[[[[_iiii_nnnn_////_oooo_uuuu_tttt _aaaa_rrrr_gggg_]]]] _aaaa_tttt_tttt_rrrr_iiii_bbbb_uuuu_tttt_eeee _vvvv_aaaa_llll_uuuu_eeee _((((_rrrr_aaaa_wwww _bbbb_yyyy_tttt_eeee_ssss_)))) _****_////
  88.         _iiii_nnnn_tttt _aaaa_mmmm______llll_eeee_nnnn_gggg_tttt_hhhh_;;;; _////_**** _[[[[_iiii_nnnn_////_oooo_uuuu_tttt _aaaa_rrrr_gggg_]]]] _llll_eeee_nnnn_gggg_tttt_hhhh _oooo_ffff _vvvv_aaaa_llll_uuuu_eeee _****_////
  89.         _iiii_nnnn_tttt _aaaa_mmmm______ffff_llll_aaaa_gggg_ssss_;;;; _////_**** _ffff_llll_aaaa_gggg_ssss _((((_bbbb_iiii_tttt_----_wwww_iiii_ssss_eeee _OOOO_RRRR _oooo_ffff _####_dddd_eeee_ffff_iiii_nnnn_eeee_ssss _bbbb_eeee_llll_oooo_wwww_)))) _****_////
  90.  
  91.      The _a_m__o_p_c_o_d_e field defines how the remaining fields are to be
  92.      interpreted and can take on one of the following values:
  93.  
  94.         _AAAA_TTTT_TTTT_RRRR______OOOO_PPPP______GGGG_EEEE_TTTT _////_**** _rrrr_eeee_tttt_uuuu_rrrr_nnnn _tttt_hhhh_eeee _iiii_nnnn_dddd_iiii_cccc_aaaa_tttt_eeee_dddd _aaaa_tttt_tttt_rrrr_''''_ssss _vvvv_aaaa_llll_uuuu_eeee _****_////
  95.         _AAAA_TTTT_TTTT_RRRR______OOOO_PPPP______SSSS_EEEE_TTTT _////_**** _ssss_eeee_tttt_////_cccc_rrrr_eeee_aaaa_tttt_eeee _tttt_hhhh_eeee _iiii_nnnn_dddd_iiii_cccc_aaaa_tttt_eeee_dddd _aaaa_tttt_tttt_rrrr_////_vvvv_aaaa_llll_uuuu_eeee _pppp_aaaa_iiii_rrrr _****_////
  96.         _AAAA_TTTT_TTTT_RRRR______OOOO_PPPP______RRRR_EEEE_MMMM_OOOO_VVVV_EEEE _////_**** _rrrr_eeee_mmmm_oooo_vvvv_eeee _tttt_hhhh_eeee _iiii_nnnn_dddd_iiii_cccc_aaaa_tttt_eeee_dddd _aaaa_tttt_tttt_rrrr _****_////
  97.  
  98.      The _a_m__e_r_r_o_r field will contain the appropriate error result code if that
  99.      sub-operation fails.  The result codes for a given sub-operation are a
  100.      subset of the result codes that are possible from the corresponding
  101.      single-attribute function call.  For example, the result code possible
  102.      from an _AAAA_TTTT_TTTT_RRRR______OOOO_PPPP______GGGG_EEEE_TTTT sub-operation are a subset of those that can be
  103.      returned from an _a_t_t_r__g_e_t function call.
  104.  
  105.      The _a_m__a_t_t_r_n_a_m_e field is a pointer to a NULL terminated string giving the
  106.      attribute name that the sub-operation should operate on.
  107.  
  108.      The _a_m__a_t_t_r_v_a_l_u_e, _a_m__l_e_n_g_t_h and _a_m__f_l_a_g_s fields are used to store the
  109.      value of the named attribute, and some control flags for that sub-
  110.      operation, respectively.  Their use varies depending on the value of the
  111.      _a_m__o_p_c_o_d_e field.
  112.  
  113.      AAAATTTTTTTTRRRR____OOOOPPPP____GGGGEEEETTTT
  114.           The _a_m__a_t_t_r_v_a_l_u_e field is a pointer to a empty buffer that will be
  115.           overwritten with the value of the named attribute.  The _a_m__l_e_n_g_t_h
  116.           field is initially the total size of the memory buffer that the
  117.           _a_m__a_t_t_r_v_a_l_u_e field points to.  After the operation, the _a_m__l_e_n_g_t_h
  118.           field contains the actual size of the attribute's value.  The
  119.           _a_m__f_l_a_g_s field may be set to the _AAAA_TTTT_TTTT_RRRR______RRRR_OOOO_OOOO_TTTT flag.  If the process has
  120.           appropriate priviledges, the ROOT namespace will be searched for the
  121.           named attribute, otherwise the USER namespace will be searched.
  122.  
  123.      AAAATTTTTTTTRRRR____OOOOPPPP____SSSSEEEETTTT
  124.           The _a_m__a_t_t_r_v_a_l_u_e and _a_m__l_e_n_g_t_h fields contain the new value for the
  125.           given attribute name and its length.  The _AAAA_TTTT_TTTT_RRRR______RRRR_OOOO_OOOO_TTTT flag may be set
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. AAAATTTTTTTTRRRR____MMMMUUUULLLLTTTTIIII((((2222))))                                                    AAAATTTTTTTTRRRR____MMMMUUUULLLLTTTTIIII((((2222))))
  137.  
  138.  
  139.  
  140.           in the _a_m__f_l_a_g_s field.  If the process has appropriate priviledges,
  141.           the ROOT namespace will be searched for the named attribute,
  142.           otherwise the USER namespace will be searched.  The _AAAA_TTTT_TTTT_RRRR______CCCC_RRRR_EEEE_AAAA_TTTT_EEEE and
  143.           the _AAAA_TTTT_TTTT_RRRR______RRRR_EEEE_PPPP_LLLL_AAAA_CCCC_EEEE flags may also be set in the _a_m__f_l_a_g_s field (but
  144.           not simultaneously).  If the _AAAA_TTTT_TTTT_RRRR______CCCC_RRRR_EEEE_AAAA_TTTT_EEEE flag is set, the sub-
  145.           operation will set the _a_m__e_r_r_o_r field to EEXIST if the named
  146.           attribute already exists.  If the _AAAA_TTTT_TTTT_RRRR______RRRR_EEEE_PPPP_LLLL_AAAA_CCCC_EEEE flag is set, the
  147.           sub-operation will set the _a_m__e_r_r_o_r field to ENOATTR if the named
  148.           attribute does not already exist.  If neither of those two flags are
  149.           set and the attribute does not exist, then the attribute will be
  150.           created with the given value.  If neither of those two flags are set
  151.           and the attribute already exists, then the value will be replaced
  152.           with the given value.
  153.  
  154.      AAAATTTTTTTTRRRR____OOOOPPPP____RRRREEEEMMMMOOOOVVVVEEEE
  155.           The _a_m__a_t_t_r_v_a_l_u_e and _a_m__l_e_n_g_t_h fields are not used and are ignored.
  156.           The _a_m__f_l_a_g_s field may be set to the _AAAA_TTTT_TTTT_RRRR______RRRR_OOOO_OOOO_TTTT flag.  If the process
  157.           has appropriate priviledges, the ROOT namespace will be searched for
  158.           the named attribute, otherwise the USER namespace will be searched.
  159.  
  160.      The _f_l_a_g_s argument to the _a_t_t_r__m_u_l_t_i call is used to control following of
  161.      symbolic links in the _p_a_t_h argument.  The default is to follow symbolic
  162.      links, _f_l_a_g_s should be set to ATTR_DONTFOLLOW to not follow symbolic
  163.      links.
  164.  
  165.      _a_t_t_r__m_u_l_t_i will fail if one or more of the following are true:
  166.  
  167.      [ENOENT]         The named file does not exist.
  168.  
  169.      [EPERM]          The effective user ID does not match the owner of the
  170.                       file and the effective user ID is not super-user.
  171.  
  172.      [ENOTDIR]        A component of the path prefix is not a directory.
  173.  
  174.      [EACCES]         Search permission is denied on a component of the path
  175.                       prefix.
  176.  
  177.      [EINVAL]         A bit other than ATTR_DONTFOLLOW was set in the _f_l_a_g
  178.                       argument.
  179.  
  180.      [EFAULT]         _P_a_t_h, or _o_p_l_i_s_t points outside the allocated address
  181.                       space of the process.
  182.  
  183.      [ELOOP]          A path name lookup involved too many symbolic links.
  184.  
  185.      [ENAMETOOLONG]   The length of _p_a_t_h exceeds {_M_A_X_P_A_T_H_L_E_N}, or a pathname
  186.                       component is longer than {_M_A_X_N_A_M_E_L_E_N}.
  187.  
  188.      _a_t_t_r__m_u_l_t_i_f will fail if:
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. AAAATTTTTTTTRRRR____MMMMUUUULLLLTTTTIIII((((2222))))                                                    AAAATTTTTTTTRRRR____MMMMUUUULLLLTTTTIIII((((2222))))
  203.  
  204.  
  205.  
  206.      [EINVAL]       A bit was set in the _f_l_a_g argument, or _f_d refers to a
  207.                     socket, not a file.
  208.  
  209.      [EFAULT]       _O_p_l_i_s_t points outside the allocated address space of the
  210.                     process.
  211.  
  212.      [EBADF]        _F_d does not refer to a valid descriptor.
  213.  
  214. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  215.      attr(1),
  216.      attr_get(2), attr_getf(2),
  217.      attr_list(2), attr_list(2)
  218.      attr_remove(2), attr_removef(2),
  219.      attr_set(2), attr_set(2)
  220.  
  221. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  222.      Upon successful completion of the _a_t_t_r__m_u_l_t_i call, a value of 0 is
  223.      returned.  Otherwise, a value of -1 is returned and _e_r_r_n_o is set to
  224.      indicate the error.  Note that the individual operations listed in the
  225.      _o_p_l_i_s_t array each have their own error return fields.  The _e_r_r_n_o variable
  226.      only records the result of the _a_t_t_r__m_u_l_t_i call itself, not the result of
  227.      any of the sub-operations.
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.